Skip to content

Docs: correct the claims, fix the rendering, add a Protocol section - #1

Merged
tactino merged 6 commits into
mainfrom
chore/artifact-readiness
Sep 11, 2026
Merged

tactino merged 6 commits into
mainfrom
chore/artifact-readiness

Conversation

@tactino

@tactino tactino commented Sep 10, 2026 •

Copy link
Copy Markdown
Member

Four changes to the documentation site: it described software that does not
exist, it had never had syntax highlighting, its build was unchecked, and it
never described the thing this project is built around.

It referenced software that does not exist

Removed. A reader following those instructions would have got nowhere, and
an artifact reviewer reads the docs before the code.

Fenced code blocks were rendering as bare <pre><code>

mkdocs.yml had no markdown_extensions section at all — so no
highlighting, and content.code.copy had nothing to attach a button to, on a
site that is almost entirely code samples. Added admonition, attr_list,
toc with permalinks, pymdownx.highlight, inlinehilite, superfences
and details.

One thing deliberately left alone. The theme feature list contains
navigation.instance, which looks like a typo for navigation.instant.
Correcting it breaks --strict: mkdocs-static-i18n cannot keep the language
switcher contextual with instant navigation on. The typo is load-bearing, so
it stays, with a comment saying why.

The build was not checked

A --strict build now runs on pull requests. Without it, a broken nav entry
or a dead internal link reaches the published site.

New: a Protocol section

The boundary between the training server and the env client is the reason
this project exists, and the site never described it. A reader could learn
how to add an environment or a policy, but not what the two processes say to
each other — or that an env client need not be Python.

The page orients rather than duplicates. SPEC.md stays in
plugrl-protocol, next to the code it describes, so the two cannot drift.
What is here is the exchange diagram, the three rules a first implementation
usually gets wrong — strict alternation, feedback env sets that need not
match the infer's, chunk-summed reward — the conformance server, and the
relationship to openpi.

Both languages, as every other page. mkdocs build --strict passes; nav
translations go from 10 elements to 11.


🤖 Generated with Claude Code

tactino and others added 4 commits September 9, 2026 15:44
The site documented a remote viewer across seven pages - a uvicorn app named
vlarl_viewer, a plugrl-monitor component, and --use-remote-viewer/--viewer-host
/--viewer-port flags. None of it exists: there is no viewer repository, and the
env client CLI has no such flags. Readers following these instructions could
only fail.

Also renames the remaining "worker" wording to "env client" to match the
package that ships today.

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
mkdocs.yml declared no markdown_extensions at all, so every fenced block on a
site made almost entirely of shell and Python rendered as bare <pre><code> -
no highlighting, and nothing for content.code.copy to attach a button to.

theme.features listed "navigation.instance", which mkdocs-material does not
have, so it was silently ignored. Correcting it to navigation.instant turns out
to break the build: mkdocs-static-i18n cannot keep the language switcher
contextual with instant loading on, and --strict fails. The typo was
accidentally load-bearing. Left out, with a comment saying why.

Also adds site_description, repo_url and edit_uri, so pages get an
"Edit this page" link.

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
deploy-pages.yml only runs on a push to main, so a pull request got no
validation at all and a broken build was first visible after merging.
--strict makes a warning - a dead link, a page missing from the nav - fail
the check rather than ship.

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
The boundary between the training server and the env client is the reason
this project exists, and the site never described it. A reader could learn
how to add an environment or a policy, but not what the two processes say
to each other, or that an env client need not be Python.

The page orients rather than duplicates: SPEC.md stays in plugrl-protocol,
next to the code it describes, so the two cannot drift. What is here is the
exchange diagram, the three rules a first implementation usually gets wrong
- strict alternation, feedback env sets that need not match the infer's,
and chunk-summed reward - the conformance server, and the relationship to
openpi.

Both languages. mkdocs build --strict passes; nav translations go from 10
elements to 11.

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
@tactino tactino changed the title Artifact readiness: licence, CI, reproducible deps, and fixes found on the way Docs: correct the claims, fix the rendering, add a Protocol section Sep 10, 2026
tactino and others added 2 commits September 10, 2026 22:17
The quickstart was the dummy policy, whose learn is a sleep. A reader
following the front page of this site could confirm two processes talk to
each other and nothing more - which is a connectivity check, not a
quickstart, and the page did not say so.

It is now FPO on HalfCheetah-v5, CPU only, which trains: episode return
climbs out of the -300s in a few minutes. The connectivity check is kept
below it, labelled as what it is.

It also states the setting that would otherwise cost someone an afternoon.
FPO learns when its rollout buffer fills or when the run ends, so at the
default buffer_size=983040 a run shorter than a million steps learns exactly
once, at the very end, and produces a single point rather than a curve.

And it stops recommending the Ray launcher flatly. That line said only "Use
plugrl-run-server-ray for Ray-based distributed launch"; the launcher needs
the dppo extra, builds its worker list from the local GPU count so a
multi-node cluster still sees one node, and its server speaks an older
dialect of the protocol. Those are now stated, with a pointer to the spec.

Both languages. mkdocs build --strict passes.

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
It had no installation section at all. It opened with `plugrl-run-server`,
which requires two packages that are not on PyPI and that the page never
mentioned cloning. A reader arriving from the front page had nowhere to go.

It now begins with the clone-and-uv-sync for both repositories, then the FPO
quickstart that actually learns, then the dummy connectivity check labelled
as what it is.

It also names the two flags that are not optional and previously were not
mentioned anywhere: --policy.device cpu, because the default is cuda and the
server dies on startup without a GPU, and --algo.buffer-size, because at the
default a short run learns once at the very end.

The troubleshooting section now covers what a new user actually hits,
including both of those.

The Ray launcher is qualified here and in the user guide rather than listed
as an equal alternative to plugrl-run-server.

Both languages. mkdocs build --strict passes.

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
@tactino
tactino marked this pull request as ready for review September 11, 2026 15:16
@tactino
tactino merged commit f93b384 into main Sep 11, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant